LLM Provider Proxy 统一代理与治理平台需求拆解
文档定位：正式需求拆解稿
适用场景：用于内部沟通、任务分派、研发排期、方案评审
背景来源：OpenClaw 在接入部分模型时，因模型名称兼容与 Provider 差异问题，无法直接调通，当前已通过代理方式临时打通。现需将该方式沉淀为统一可复用能力，服务后续所有标准化产品。
1. 背景与问题
1.1 当前背景
在近期 OpenClaw 接入过程中，主要问题并不完全来自模型能力本身，而是来自不同 LLM Provider 之间的兼容性差异，尤其体现在：
- 模型名称不一致
- API 路径和协议不完全一致
- 请求参数定义存在差异
- 返回结果格式存在差异
- 鉴权方式和访问入口不一致
上述问题导致 OpenClaw 无法直接稳定调通目标模型，最终通过增加代理层的方式完成了适配和转发。
1.2 当前问题
目前这套代理方式仍然偏临时方案，存在以下问题：
- 适配逻辑可能散落在临时代码中，难以复用
- 模型映射关系不统一，后续维护成本高
- 缺少统一的 Provider 抽象与接入规范
- 缺少计费、审计、调用追踪等平台能力
- 无法直接复用到后续其他标准化产品中
1.3 建设动因
本次需求不应只停留在“解决 OpenClaw 调通问题”，而应借此沉淀一层统一的 LLM Provider Proxy / Gateway 能力，用于支撑后续所有标准化产品的模型接入、路由、治理、审计和计费。
2. 建设目标
2.1 总体目标
建设一套统一的 LLM Provider Proxy / Gateway，屏蔽底层不同模型厂商之间的差异，为上层标准化产品提供统一、稳定、可管控的模型调用入口。
2.2 近期目标
优先解决当前 OpenClaw 场景中的接入问题：
- 支持通过统一代理方式接入目标模型
- 支持模型名称映射与兼容转换
- 尽量减少上层系统改造成本
- 形成可复用、可配置、可部署的代理服务
2.3 中长期目标
在完成当前接入适配后，逐步演进为面向所有标准化产品的统一模型能力底座，支撑：
- 多 Provider 统一接入
- 逻辑模型名与实际模型名解耦
- 权限、配额与租户隔离
- 统一调用审计
- 统一计量计费
- 统一监控运维与稳定性治理
3. 建设范围
本次需求建议覆盖以下六大能力模块。
3.1 Provider 接入适配能力
目标
对不同 LLM Provider 的接口差异进行统一封装，使上层系统使用统一调用方式，无需感知底层 Provider 差异。
需求点
- 支持统一协议入口，优先兼容 OpenAI-compatible 调用方式
- 支持不同 Provider 的 API 路径适配
- 支持请求参数转换
- 支持返回结果标准化
- 支持模型名称映射
- 支持后续扩展多个 Provider
典型场景
- 上游传入统一模型名，代理层自动映射为真实模型名
- 上游使用统一请求结构，代理层负责转发到不同厂商接口
- 底层返回格式不一致时，代理层统一封装返回结果
3.2 模型注册与路由管理能力
目标
建立统一的模型注册、别名映射与路由管理机制，避免模型配置散落在业务代码中。
需求点
- 支持逻辑模型名配置
- 支持实际 Provider 模型名映射
- 支持模型别名管理
- 支持默认路由配置
- 支持备用路由配置
- 支持按产品配置可用模型白名单
- 支持模型下线、切换、升级时的平滑调整
典型示例
逻辑模型名：general-chat
实际路由：
- 首选：Provider A / qwen-plus
- 备选：Provider B / gpt-4.1-mini
- 兜底：Provider C / deepseek-chat
上层系统只使用 general-chat，不直接依赖底层真实模型名。
3.3 认证、权限与隔离能力
目标
对代理层的调用方进行统一识别和授权管理，支持后续多产品、多团队、多租户共享使用。
需求点
- 支持调用方身份识别
- 支持 API Key / Token 管理
- 支持按产品、环境、租户分配权限
- 支持模型调用白名单控制
- 支持限流与调用配额控制
- 支持后续多租户隔离扩展
适用场景
- 不同产品只能调用指定模型
- 内部测试环境和正式环境使用不同模型权限
- 外部客户环境禁止使用非白名单模型
3.4 计量计费能力
目标
在统一代理层沉淀模型调用的成本数据，为后续内部结算、成本分析和产品计费提供基础。
需求点
- 记录调用次数
- 记录输入 token、输出 token
- 记录模型调用时长、响应延迟
- 记录调用成功/失败状态
- 支持成本估算
- 支持按产品、模型、时间范围统计
- 支持对账基础数据导出
产出价值
- 统一掌握模型资源消耗情况
- 支撑内部成本归集
- 为后续商业化计费做准备
3.5 审计与追踪能力
目标
对所有模型调用形成可追溯、可排查、可审计的记录体系。
需求点
- 记录调用时间
- 记录调用方
- 记录请求模型与实际路由模型
- 记录请求参数摘要
- 记录返回状态与错误信息
- 记录 token 消耗和耗时
- 支持 trace_id 全链路跟踪
- 支持日志脱敏
- 支持问题排查与调用回溯
说明
对于正式产品场景，审计能力不仅用于问题排查，也用于安全留痕、运营分析和合规管理。
3.6 运维监控与稳定性治理能力
目标
保障代理层长期稳定运行，支持后续平台化运营。
需求点
- 支持 Provider 健康检查
- 支持调用量、成功率、失败率监控
- 支持时延监控
- 支持高频错误分析
- 支持告警能力
- 支持超时、重试、熔断、降级等策略
- 支持 fallback 路由能力
价值
使代理层从“能转发”升级为“可长期运行的基础设施能力”。
4. 需求边界
4.1 本期建议纳入范围
- OpenClaw 场景接入打通
- Provider 代理与模型名称映射
- 统一协议转发
- 基础配置管理
- 基础审计埋点
- 基础调用统计
- 后续平台化扩展设计
4.2 本期可暂不纳入范围
- 复杂可视化运营后台
- 完整商业化计费结算系统
- 多区域多集群调度
- 全量模型能力评测系统
- 完整租户管理后台
说明：本期建议以“先落地可用、再逐步平台化”为原则，避免首期建设范围过大。
5. 分期建设建议
5.1 第一期：打通可用
建设目标
优先解决 OpenClaw 与现有产品的模型接入问题，形成最小可用代理服务。
核心范围
- Provider 代理转发
- 模型名称映射
- 统一 OpenAI-compatible 接口
- 基础配置管理
- 基础日志与审计字段
- 基础部署能力
阶段关键词
先打通，先可用，先沉淀基本形态
预期交付
- 可部署的代理服务
- 模型映射配置
- OpenClaw 接入说明
- 基础调用日志与问题排查能力
5.2 第二期：统一可管
建设目标
将代理层升级为多个产品可共享的统一网关。
核心范围
- 模型注册中心
- Provider 配置管理
- API Key / Token 管理
- 调用权限与模型白名单控制
- 配额与限流能力
- 基础统计报表
- 成本统计能力
阶段关键词
从临时代理，升级为统一网关
预期交付
- 模型注册与映射机制
- 权限与调用控制机制
- 基础统计与成本报表
- 统一接入规范
5.3 第三期：平台可运营
建设目标
形成面向标准化产品的统一 LLM 能力底座。
核心范围
- 多 Provider 智能路由
- fallback / 熔断 / 降级机制
- 多租户支持
- 计费规则扩展
- 审计中心
- 运营监控面板
- 稳定性治理与 SLA 支撑
阶段关键词
从统一网关，升级为模型基础设施平台
6. 功能清单
6.1 接入适配
- 多 Provider 接入
- 统一调用协议
- 模型名称映射
- 参数转换
- 返回结果标准化
6.2 路由管理
- 逻辑模型名配置
- 实际模型路由配置
- 默认路由配置
- 备用路由配置
- 模型白名单
6.3 鉴权与权限
- 调用方识别
- API Key 管理
- 产品级权限控制
- 模型调用授权
- 限流与配额
6.4 计量计费
- token 统计
- 调用次数统计
- 成本估算
- 分产品统计
- 分模型统计
- 对账数据导出
6.5 审计追踪
- 请求留痕
- 响应状态记录
- trace_id 跟踪
- 错误日志
- 脱敏审计
6.6 运维监控
- 调用量监控
- 成功率/失败率监控
- 延迟监控
- Provider 健康检查
- 告警能力
- 熔断与 fallback
7. 非功能要求
7.1 兼容性
- 对 OpenClaw 接入尽量低侵入
- 对后续标准化产品提供统一接入方式
- 对不同 Provider 保持可扩展兼容
7.2 可配置性
- 模型映射关系不能写死在业务代码中
- Provider 配置支持统一维护
- 路由策略支持动态调整
7.3 可扩展性
- 新增 Provider 时尽量不改核心代码
- 计费、审计、权限等能力支持模块化扩展
7.4 安全性
- Provider Key 安全存储
- 调用日志支持脱敏
- 敏感请求内容避免明文裸存
7.5 稳定性
- 支持超时控制
- 支持失败重试
- 支持 fallback 与熔断
- 保证核心转发链路可观测、可恢复
8. 建议的数据记录字段
建议从第一期开始，统一记录以下基础字段，为后续计费、审计和运营分析打底。
8.1 调用基础信息
- request_id
- trace_id
- 调用时间
- 调用方标识
- 产品标识
- 环境标识
8.2 模型与路由信息
- 请求模型名
- 逻辑模型名
- 实际 Provider
- 实际模型名
- 路由策略
8.3 调用结果信息
- 请求状态
- 错误码
- 错误摘要
- 总耗时
- Provider 响应耗时
8.4 资源消耗信息
- prompt_tokens
- completion_tokens
- total_tokens
- 成本估算
8.5 审计信息
- 请求摘要
- 返回摘要
- 脱敏标记
- 操作人/系统来源
9. 对研发的具体任务建议
为避免需求表达过于抽象，建议拆为以下四类任务。
任务一：临时方案工程化
将当前为 OpenClaw 打通的代理方式整理为独立可部署服务，避免继续以一次性脚本或零散代码存在。
目标
- 服务化
- 配置化
- 可复用
- 可部署
任务二：Provider 抽象与模型映射沉淀
把本次暴露出来的模型名称兼容问题，抽象为通用模型路由和名称映射能力。
目标
- 逻辑模型名与实际模型名分离
- 多 Provider 抽象统一
- 模型映射配置集中管理
任务三：计费与审计基础埋点
在代理链路上增加基础埋点能力，为后续成本分析、对账和问题追踪提供数据基础。
目标
- 记录调用方、模型、token、耗时、状态
- 支持基础成本估算
- 支持基础审计查询
任务四：平台化演进设计
在交付代码的同时，补充后续演进设计，避免再次出现“能用但难扩展”的情况。
目标
- 输出模块划分
- 输出配置设计
- 输出数据表设计建议
- 输出分期演进路线
- 输出主要风险点
10. 预期交付物
本次需求建议最终交付以下内容：
10.1 代码与服务
- 统一代理服务代码
- Provider 接入适配模块
- 模型映射与配置模块
- 基础日志与审计埋点
10.2 文档
- 部署说明文档
- 接入说明文档
- 配置说明文档
- 常见问题与排障文档
- 平台化演进设计文档
10.3 配置与样例
- Provider 配置样例
- 模型映射样例
- OpenClaw 接入样例
- 审计字段样例
10.4 数据与统计基础
- 调用日志结构
- token 统计结构
- 成本估算结构
- 审计查询基础结构
11. 风险与注意事项
11.1 需求风险
若只关注“模型名称适配”，容易再次形成一次性补丁方案，无法服务后续产品。
11.2 技术风险
不同 Provider 的返回结构、限流策略、计费口径可能存在差异，需要在抽象设计时预留弹性。
11.3 运维风险
若缺少监控、告警、日志和 fallback 机制，代理层会成为新的单点风险。
11.4 安全风险
若 Key 管理、日志脱敏、请求留痕处理不规范，容易带来数据安全与审计风险。
12. 结论
本次需求的本质，不是为 OpenClaw 做一次临时兼容，而是借当前模型接入问题，沉淀一层面向未来所有标准化产品的统一 LLM Provider Proxy / Gateway 能力。
建议建设思路为：
- **第一步，先解决当前接入问题，形成最小可用代理服务；**
- **第二步，把代理层升级为统一可管的模型网关；**
- **第三步，逐步沉淀为具备路由、权限、计费、审计和运维能力的统一模型基础设施。**
这样既能解决当前实际问题，也能避免后续各产品重复建设、重复踩坑。
附：建议的正式需求标题
可选标题一：
标准化产品统一 LLM Provider 代理与治理平台建设需求
可选标题二：
LLM Provider Proxy 统一接入、路由、计费与审计能力建设需求
可选标题三：
面向标准化产品的统一模型代理网关建设需求拆解